home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 June / Macworld (1998-06).dmg / Shareware World / Info / For Developers / MacsBug 6.5.4a4 / MacsBug 6.5.4a4 Read Me < prev    next >
Text File  |  1998-02-11  |  22KB  |  456 lines
  1.  About MacsBug 6.5.4a4
  2.    2/3/98
  3.  
  4.     INSTALLATION INSTRUCTIONS
  5.  
  6.     • MacsBug includes a number of folders. The contents of each is as follows:
  7.  
  8.         "into System Folder" - This contains MacsBug itself. To install, place the "MacsBug" file
  9.         into your System folder and restart your machine.
  10.  
  11.         "into MacsBug Preferences folder" - This contains optional dcmds. Currently, the only
  12.         optional dcmd is the Leaks dcmd. It is no longer included within MacsBug because it
  13.         patches a number of Memory Manager traps with 68K code, potentially slowing down
  14.         the system. To install, copy the Leaks file into your "MacsBug Preferences" folder which
  15.         is located in your "Preferences" folder.
  16.  
  17.         "into Debugger Prefs file" - This contains the standard U.S. 'KCHR' keyboard translation
  18.         resource. It is needed when using MacsBug to debug on a system that is using a non-U.S.
  19.         keyboard layout (MacsBug requires U.S. keyboard translation). To install, copy the
  20.         'KCHR' resource from this file into your "Debugger Prefs" file which must be located in
  21.         the System folder.
  22.  
  23.         "Building dcmds" - This contains sample C and Pascal source for a variety of dcmds, as
  24.         well as all headers and libraries necessary to build dcmds within the MPW environment.
  25.  
  26.     • The set of dcmds that has been included with MacsBug in the optional file "PowerPC
  27.     dmcds" has been merged into MacsBug itself. When installing MacsBug, you should make
  28.     sure to remove this file from your "MacsBug Preferences" folder.
  29.  
  30.     • When MacsBug is first entered, it displays a message if it has encountered dcmds that have
  31.     the same name. If you see this message, you should examine all of your preference files and
  32.     remove any duplicates. MacsBug does not guarantee which dcmd is executed when a name
  33.     collision occurs, so you may be accidentally using an old dcmd.
  34.  
  35.  
  36.     VIDEO DISPLAY CHANGES
  37.  
  38.     • MacsBug's video display capabilities have been greatly enhanced, and it can now work in 
  39.     any bit depth. By default, MacsBug still tries to switch into the lowest bit depth your
  40.     display device supports. However, a new option has been added to the 'mxpr' preference
  41.     resource, "Don't swap display bit depth", which tells MacsBug to never attempt depth
  42.     switches. This means that when MacsBug is active on the screen, it will remain in the
  43.     same bit depth Mac OS is presently in.
  44.  
  45.     Normally MacsBug determines at startup what the minimum depth your display will
  46.     support, and allocates its video buffer for that depth. However, when you enable the
  47.     "Don't swap display bit depth" feature, MacsBug has to be prepared for any of the depths
  48.     your display supports, so it allocates a maximum-sized buffer. Note that enabling this
  49.     mode will likely significantly increase MacsBug's memory requirements. For example,
  50.     when your display supports millions of colors, MacsBug will allocate an offscreen
  51.     buffer that consumes 1,200K of RAM.
  52.  
  53.     When the "Don't swap display bit depth" feature is enabled, MacsBug, for the first time,
  54.     properly supports display depth changes across invocations. When you leave MacsBug and
  55.     re-enter in a different depth, there may be a pause of a second or two while MacsBug re-
  56.     initializes its offscreen buffer.
  57.  
  58.     • MacsBug now knows how to turn back on most power-managed display devices. If, for
  59.     example, the display MacsBug is using powers off while you're away, and your machine
  60.     eventually crashes (for whatever reason), MacsBug will attept to turn it back on when it
  61.     gets control.
  62.  
  63.  
  64.     TEXT COLORIZATION
  65.  
  66.     • MacsBug now supports drawing text in certain hilight colors to attempt to draw your eye
  67.     to interesting display changes. The initial implementation shows registers that change as
  68.     you step in a hilighted color. By default this is 100% RGB red, but can be customized via
  69.     a 'clut' (Color lookup table) resource. The default 'clut' is located in MacsBug, and
  70.     should be copied to your "Debugger Prefs" file if you wish to modify it. The meaning of
  71.     each color entry is as follows:
  72.  
  73.             0 - background color - Usually white. If a classic 'mxbc' (MacsBug color)
  74.                  resource is present, this value is overridden from it.
  75.  
  76.             1 - normal text foreground - Usually black. If a classic 'mxbc' (MacsBug color)
  77.                  resource is present, this value is overridden from it.
  78.  
  79.             2 - primary hilight color - Text is drawn in a noticeable color to draw attention
  80.                   to it. This is used to color registers as they change while stepping.
  81.  
  82.             3 - secondary hilight color - Text is drawn in a noticeable color to draw attention
  83.                  to it, but to a lesser degree than the primary hilight color. This is not used in
  84.                   MacsBug 6.5.4a4.
  85.  
  86.     Colorization is enabled if the MacsBug display is in any depth greater than 1. If you
  87.     want to disable colorization, a new 'mxpr' preferences resource bit has been added. Set
  88.     the "Don't colorize text" bit to disable color.
  89.  
  90.  
  91.     STACK CRAWL
  92.  
  93.     • Both the SC6 and SC7 stack crawls were unreliable on the most recent 8600 and 9600
  94.     machines (those with an inline cache controller, such as the 8600/250, 8600/300,
  95.     9600/300, and 9600/350). MacsBug is now more defensive when examining addresses on the
  96.     stack, and should no longer lock up those machines.
  97.  
  98.  
  99.     COMMAND LINE
  100.  
  101.     • When you hit a function key and the command line is not empty, the key enters its name
  102.     with a trailing blank, rather than automatically hitting Return for you. This is useful
  103.     when defining a function-key macro. For example, to make the F12 function key do nothing:
  104.  
  105.             MC DoF12 ''
  106.  
  107.     (DoF12 was entered by simply hitting the F12 key.)
  108.  
  109.     • Command-zero is now a parenthesis-matching demon. If you've typed out an expression,
  110.     hitting Command-0 inserts a close-paren at the current insertion location, and a matching
  111.     open-paren after the closest whitespace (or at the beginning of the command line).
  112.  
  113.     • A new SET option, ECHO, has been added that enables or disables echoing of each command
  114.     you type into the history area. If ECHO is on, hitting return to execute the command
  115.     prints it into the history area like this:
  116.  
  117.             >>> dm a0 iopb
  118.  
  119.     • A change was made to MacsBug 6.5.3 that disallowed whitespace in binary subtraction
  120.     expressions such as "4 - 3" (this was made invalid). This was done to allow commands with
  121.     "-" options to properly parse their parameters. However, if you happened to type an
  122.     expression in this invalid form, the error was pretty poor (it used to say "The template
  123.     contains an unrecognized data type"). It now says something much more useful (using the
  124.     "4 - 3" example):
  125.  
  126.             Expected a data type after the expression
  127.             Note: Command did not use all parameters ("- 3")
  128.             Note: To subtract, there must be no space before the '-'
  129.  
  130.  
  131.     DEBUGSTR
  132.  
  133.     • DebugStr now supports an option where you can programmatically turn the DX state
  134.     (Debugger breaks) back to "on". Previously, once DX had been turned off, all commands
  135.     that are part of a DebugStr string (everything after the first ';') were ignored. If the
  136.     string passed to DebugStr is exactly ";DX ON" (ignoring case), user breaks will be re-
  137.     enabled starting with the next DebugStr.
  138.  
  139.  
  140.     DISASSEMBLY
  141.  
  142.     • Both the PowerPC and 68K disassemblers no longer cause command line processing to
  143.     terminate if they are passed invalid addresses (odd, unmapped, etc.).
  144.  
  145.  
  146.     HEAP COMMANDS
  147.  
  148.     • The HS (Heap Scrambling) command was broken in MacsBug 6.5.4a3c1 such that once you
  149.     enabled it, you could never disable it. This has been fixed.
  150.  
  151.     • The HC (Heap Check) command has been fixed to stop ignoring three specific types of
  152.     heap corruption. These are:
  153.  
  154.             - For non-relocatable blocks, if the heap header pointer doesn't point to the correct
  155.                 heap.
  156.             - For relocatable blocks, if the address of the master pointer is not in the
  157.                 correct heap.
  158.             - For relocatable blocks, if the master pointer does not point to the heap block.
  159.  
  160.     These errors have been detected by the HZ (Heap Zones) and HD (Heap Dump) commands
  161.     when "!" was displayed beside a heap, or a "!" or "?" was displayed beside a heap block.
  162.     However, if you used HC on the heap in question, it would say everything was fine. This
  163.     has been fixed (and seems to have been broken for at least seven years).
  164.  
  165.     • When the HZ and HC commands operate on the first embedded heap in the System heap
  166.     (called the ROZ - or ROM read-only zone), MacsBug no longer calls it corrupt for certain
  167.     valid oddities. In the future, if it does show up corrupt, it likely is damaged.
  168.  
  169.     • The HP (Heap Profile) command has been enhanced a bit. It now shows the size of blocks in
  170.     K, and allows the "-i" (increment) and "-c" (minimum count) options to be used together.
  171.  
  172.  
  173.     LOGGING
  174.  
  175.     • When the LOG command is asked to write to a pre-existing log file, it appends. However,
  176.     it used to change the type and creator to be an MPW text file. When appending, MacsBug
  177.     now leaves the type and creator alone.
  178.  
  179.  
  180.     MACROS
  181.  
  182.     • Help on a macro now shows the full expansion when more than one layer of macro
  183.     expansion is required. A good example of this in action is the StdLog macro. Typing
  184.     "help StdLog" results in:
  185.  
  186.             STDLOG is a macro which expands to:
  187.                         StdLogInto StdLog
  188.             The full expansion is:
  189.                         log "StdLog";set suspendprompt on;dv v;stat;wh;td;ip;hz;hc
  190.                         all;ht;hx;ht;hx; file 0;rd -s;sc6;sc7 sp 1k;dm 0 20;log
  191.  
  192.     Notice that StdLog is a macro which uses the StdLogInto macro which takes one parameter,
  193.     the name of the log file.
  194.  
  195.  
  196.     MEMORY COMMANDS
  197.  
  198.     • When displaying a memory location via DB (Display Byte), DW (Display Word), or DL
  199.     (Display Long), MacsBug now does its normal "explain significance of", where it
  200.     shows you the magnitude or other interesting characteristics of the value displayed.
  201.  
  202.     • Words and longs can now be written to odd locations with the SW (Set Word) and SL (Set
  203.     Long) commands. The restriction was only for the 68000, which we no longer support (the
  204.     68020 and later have no such restriction).
  205.  
  206.  
  207.     MISCELLANEOUS COMMANDS
  208.  
  209.     • A number of commands which set an on or off state now support a third option, "now",
  210.     which tells you the current state of the command without changing it. The commands that
  211.     have this new option are ATR (A-Trap Record), DSCX (Discipline Breaks), SX (Symbol
  212.     Exchange), RAD (Register An display), DX (Debugger breaks), and SET (Set MacsBug option).
  213.  
  214.  
  215.     PREFERENCES
  216.  
  217.     • Two new bits have been defined in the 'mxpr' (MacsBug preferences) "danger bits" field.
  218.     Setting the "Relax PowerPC embedded symbol limits" bit makes MacsBug's PowerPC symbol
  219.     lookup less strict by allowing the characters '(', ';', ')', '/', and '[' to appear in
  220.     symbols. This was added for MRJ. The second bit, "Don't use simplified PowerPC
  221.     mnemonics", defaults the PowerPC disassembly to not display mnemonics in simplified form.
  222.     You can change this at runtime with the SET SIMPLIFIED command.
  223.  
  224.  
  225.     RS/RB
  226.  
  227.     • The RS (Unmount all volumes except servers and reboot) and the RB (Unmount just the
  228.     boot volume and reboot) commands have been unreliable when running certain
  229.     combinations of OS releases and extensions. MacsBug now goes to some length to avoid
  230.     calling anything but the ROM-based ShutDown Manager to restart the machine (thus
  231.     avoiding any patches that may have been applied to the ShutDown trap). If you had seen
  232.     "MacsBug caused the exception" after invoking RS or RB, this should now be fixed.
  233.  
  234.  
  235.     SYMBOL LOOKUP
  236.  
  237.     • We now limit the extent of memory searched for embedded 68K and PowerPC symbols to
  238.     64K for performance reasons, rather than the entire size of each heap block being searched. 
  239.  
  240.  
  241.     TEMPLATES
  242.  
  243.     • A new template basic type has been added that interprets a 16-bit word as a volume
  244.     reference number. VRefNum attempts to find and display the volume name associated with
  245.     the specified number. For example, if you type:
  246.  
  247.             -1 vRefNum
  248.  
  249.     MacsBug responds with the name of the associated volume, such as:
  250.  
  251.             FFFF = Starlust
  252.  
  253.     • A new template basic type has been added that interprets three 16-bit words as an RGB
  254.     color. The RGBColor type uses the same amazing color-naming technology that's found in
  255.     Mac OS 8's Crayon color picker. For example, displaying the memory location 123456 as
  256.     an RGBColor yields:
  257.  
  258.             DM 123456 RGBColor
  259.  
  260.             Displaying RGBColor
  261.               00123456  FFFF 2222 0000 [Red Orange-ish]
  262.  
  263.  
  264.     TRANSITION VECTOR COMMANDS
  265.  
  266.     • The TVC (Transition Vector Clear) command now supports clearing individual actions by
  267.     name. All actions with the given name will be cleared. It does not yet support the
  268.     library name syntax that the Transition Vector set action commands allow.
  269.  
  270.     • We now support TVector commands on addresses as well as symbols.
  271.  
  272.  
  273.     WATCH POINTS
  274.  
  275.     • It's clear that they are less than reliable; sometimes they work, and sometimes your
  276.     machine freezes hard. This version of MacsBug does not address this at all, so you should
  277.     be aware that they may not work. A future version will replace the underlying Watch Point
  278.     mechanism with a much more robust architecture.
  279.  
  280.  
  281.     MISCELANEOUS
  282.  
  283.     • Updated the TD (Total register display) command for PowerPC to have better names for the
  284.     PowerPC 740/750 (Arthur) and 604ev (Mach-5) processors.
  285.  
  286.     • Made a number of minor changes to better work on the Blue Box. This makes logging and
  287.     RS/RB work correctly. None of the changes are active on any other machines.
  288.  
  289.     • The STAT command and SECONDS basic type now show the year as 4 digits instead of 2,
  290.     making MacsBug year 2000-savvy. This saves the Macintosh industry approximately $430
  291.     million (U.S.) per year, according to current U.S. Department of Labor statistics.
  292.  
  293.     • MacsBug's hooks into the keyboard input mechanism are now installed the entire time
  294.     MacsBug is active, not just while it's reading the keyboard. This means that you should
  295.     no longer see keys "leaking" from MacsBug into the frontmost application.
  296.  
  297.     • The 'ß' character (option-s) is now shorthand notation for kabillion in a hex number.
  298.     "FFCß" is equivalent to FFC00000, which is pronounced "eff-eff-see kabillion". For those
  299.     of you new to kabillion notation, it's a shorthand means to describe a 32-bit number that
  300.     has a lot of zeros in the least-significant digits (those on the right). MacsBug uses
  301.     kabillion notation when describing a 32-bit number that has at least 5 nibbles of zeros.
  302.  
  303.     • Fixed a nasty synchronization problem between MacsBug’s A-Trap exception handler
  304.      and the code responsible for handling NMIs. If you had any A-Trap actions pending, and
  305.      you NMIed a number of times, it was likely that you would eventually crash within
  306.      MacsBug.
  307.  
  308.     DCMD BUILDING AND SUPPORT
  309.  
  310.     • The TestDcmd application that has been included with MacsBug as a framework to debug
  311.     dcmds has been removed. It has been superceded by MacsBugApp, the application version of
  312.     MacsBug.
  313.  
  314.     • Cleaned up the dcmd formatting library interface (put.h) a bit. Removed the
  315.     unimplemented function PutInit. Updated the functions PutPStrTruncTo, PutPStrTo,
  316.     and PutPStr to require ConstStr255Params so as to be more correct. Changed a bunch of
  317.     parameters to be UInt16 or UInt32. Added a new function, PutMemoryLine, which
  318.     displays a line of memory formatted like MacsBug's built-in DM (Display Memory)
  319.     command.
  320.  
  321.  
  322.     DCMDS
  323.  
  324.     • When the execution of a dcmd is aborted (by hitting a key while a dcmd is displaying
  325.     output), the area in the upper-left corner of the display (controlled by the SHOW
  326.     command) no longer partially erases.
  327.  
  328.     • Cache
  329.  
  330.     This is a new dcmd. Cache shows what files have disk blocks in the File Manager's disk
  331.     cache, where those blocks are in the file and on disk, and the state of those blocks
  332.     (clean/dirty, in use/not, contains valid data/not). Cache also shows free blocks that
  333.     aren't associated with an open file, but contain valid data, and shows some general cache
  334.     statistics (size, hits, misses, etc.). Developers of FSM-based file systems will find
  335.     this dcmd very useful.
  336.  
  337.     • CFI
  338.  
  339.     The functionality of the CFI (Code Fragment Info) dcmd has been merged into the Frags
  340.     dcmd (see the "-r" option), so CFI is no longer included in MacsBug.
  341.  
  342.     • Drvr
  343.  
  344.     Added a new option, "-b", which only displays information on drivers that are currently
  345.     busy.
  346.  
  347.     • EBBE
  348.  
  349.     The sleep queue procedure can now handle requests it doesn't understand. This makes
  350.     certain machines sleep when the EBBE dcmd is active.
  351.  
  352.     Added a new option, "now", which tells you the current state of EBBE (on or off)
  353.     without changing it.
  354.  
  355.    • File
  356.  
  357.     Added a new option, "-p", which shows the files that have been opened by a given
  358.     application process.
  359.  
  360.     • Frags
  361.  
  362.     Added a new option, "-r", that displays files and fragments registered with the Code
  363.     Fragment Manager. These are registered with the CFM during system startup, but are not
  364.     necessarially currently being used.
  365.  
  366.     • Gestalt
  367.  
  368.     Added a few more selectors to the list of those that we won't call because they make
  369.     toolbox calls that don't work in the dcmd environment. Newly added are 'rdsk', 'irhw',
  370.     and 'tabl'. Added a description of the 'cpuf' (gestaltNativeCPUFamily) selector.
  371.  
  372.     • Leaks
  373.  
  374.     The Leaks dcmd is no longer included within MacsBug since it patches a number of Memory
  375.     Manager traps with 68K code, potentially slowing down the system. It is now provided as
  376.     an optional dcmd in its own file.
  377.  
  378.     • PowerPC dcmds
  379.  
  380.     The dcmds which were part of the optional file "PowerPC dcmds" have now been merged into
  381.     MacsBug so they will always be available. The newly-moved dcmds include:
  382.  
  383.             atvb - break on toolbox calls by patching the trap table, not the 68K A-Trap
  384.                          dispatcher (deprecated - use TVector commands instead)
  385.             cfm - display information on Code Fragments (deprecated - use Frags instead)
  386.             findsym - show all instances of a given CFM symbol, including each TVector
  387.             pp - parse, validate, and display a Mixed Mode proc info
  388.             r2db - break into the two-machine debugger
  389.  
  390.     • QCheck
  391.  
  392.     Added a new option, "now", which tells you the current state of QCheck (on or off)
  393.     without changing it.
  394.  
  395.     • StopAS
  396.  
  397.     This is a new dcmd. StopAS replaces the StopXPP dcmd, which only worked on AppleTalk
  398.     connections. StopAS attempts to close AppleShare sessions on both AppleTalk and TCP
  399.     connections. StopXPP is now a macro defined as StopAS.
  400.  
  401.     • VMDump
  402.  
  403.     The page hold and lock counts are now shown for ranges within file map space. Added a
  404.     "-b" option to show valid/invalid state of backing pages on disk. Added a count of
  405.     resident pages to the "-f" (file map) table. Added counts at the end of VMDump showing
  406.     number of InMemory pages, NotPaged pages, OnDisk pages, and contiguous OnDisk ranges
  407.     within the address range dumped.
  408.  
  409.  
  410.     TEMPLATES AND MACROS AND FRIENDS
  411.  
  412.     • To support the new colorization mechanism, a 'clut' resource (ID 128) has been added to
  413.     MacsBug. If you want to modify this, copy it into your "Debugger Prefs" file. The ID must
  414.     be 128.
  415.  
  416.     • The default 'mxbc' (MacsBug color) resource has been removed from MacsBug since the
  417.     'clut' now provides foreground and background color control.
  418.  
  419.     • Updated the machine names list by adding the following:
  420.  
  421.             PowerBook 2400
  422.             PowerBook G3
  423.             PowerMac G3
  424.             PowerMac 5500
  425.             PowerMac 6500
  426.             PowerMac 4400
  427.  
  428.     • Changed the GrafPort and CGrafPort templates to no longer skip the spExtra field. We
  429.     don't have a Fixed data type, but we can at least show it as hex.
  430.  
  431.     • Fixed the AppParameters template to no longer reference an undefined type, making it
  432.     work again. This makes the LaunchParamBlockRec template work as well, since it has a
  433.     pointer to an AppParameters template as its last field.
  434.  
  435.     • Added a new enum, E2_FSID, and populated it with all of the existing external file
  436.     systems. Updated the VCB and DrvQEl templates to use this new enumeration.
  437.  
  438.     • Added a new enum, E4_DirID, and populated it with the pre-defined directory IDs (root of
  439.     parent and parent). Changed the FSSpec template to use the new E4_DirID enumeration.
  440.  
  441.     • Added a missing filler word in the IPCListPortParams template.
  442.  
  443.     • Added two missing SoundDispatch calls: OpenMixerSoundComponent and
  444.     CloseMixerSoundComponent.
  445.  
  446.     • Added missing Component Manager calls: OpenAComponent, OpenADefaultComponent,
  447.     and OpenAComponentResFile.
  448.  
  449.  
  450.  
  451. © 1998 Apple Computer, Inc. All rights reserved.
  452.  
  453. Apple, the Apple logo, Apple IIGS, AppleShare, AppleTalk, Macintosh, MPW, Power Macintosh, PowerBook,
  454. QuickDraw, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries.
  455. Sound Manager is a  trademark of Apple Computer, Inc. PowerPC is a trademark of International Business Machines
  456. Corporation, used under license therefrom.